\# Author Andy Pugh
\# Issued under the terms of the GPL v2 License or any later version
.TH MATRIX_KB "9" "2013-03-24" "LinuxCNC Documentation" "HAL Component"
.de TQ
.br
.ns
.TP \\$1
..

.SH NAME

matrix_kb \- Convert integers to HAL pins. Optionally scan a matrix of IO ports
to create those integers.  
.SH SYNOPSIS
.B loadrt matrix_kb config=\fIRxCs,RxCs\fB... names=\fIname1,name2\fB...
.P
Creates a component configured for R rows and N columns of matrix keyboard. 

If the \fBs\fR option is specified then a set of output rows will be cyclically
toggled, and a set of input columns will be scanned. 

The \fBnames\fR parameter is optional, but if used then the HAL pins and functions
will use the specified names rather than the default ones. This can be useful
for readbility and 2-pass HAL parsing. 

There must be no spaces in the parameter lists. 

.SH DESCRIPTION

This component was written to convert matrix keyboard scancodes into HAL pins. 
However, it might also find uses in converting integers from 0 to N into N HAL
pins. 

The component can work in two ways, and the HAL pins created vary according to
mode. 

In the default mode the component expects to be given a scan code from a
separate driver but could be any integer from any source. Most typically this
will be the keypad scancode from a Mesa 7i73. The default codes for keyup and
keydown are based on the Mesa 7i73 specification with 0x40 indicating a keydown
and 0x80 a keyup event. 
 If using the 7i73 it is important to match the keypad size
jumpers with the HAL component. Valid configs for the 7i73 are 4x8 and 8x8. 
Note that the component will only work properly with the version 12 (0xC) 7i73
firmware. The firmware version is visible on the component parameters in HAL.

In the optional scan-generation mode the \fBmatrix_kb.\fIN\fB.keycode\fR pin 
changes to an output pin and a set of output row pins and input column pins are
created. 
These need to be connected to physical inputs and outputs to scan the matrix and
return values to HAL. Note the \fBnegative\-logic\fR parameter described below,
this will need to be set on the most common forms of inputs which float high
when unconnected.  

In both modes a set of HAL output pins are created corresponding to each node of
the matrix.

.SH FUNCTIONS
.TP
.B matrix_kb.\fIN\fR
Perform all requested functions. Should be run in a slow thread for effective
debouncing. 
.SH PINS
.TP
.B matrix_kb.\fIN\fB.col\-\fICC\fB\-in\fR bit in
The input pin corresponding to column C.
.TP
.B matrix_kb.\fIN\fB.key.r\fIR\fBc\fIC\fR bit out
The pin corresponding to the key at row R column C of the matrix. 
.TP
.B matrix_kb.\fIN\fB.keycode\fR unsigned in or out depending on mode. 
This pin should be connected to the scancode generator if hardware such as a 
7i73 is being used. In this mode it is an input pin. In the internally-generated
scanning mode this pin is an output, but will not normally be connected. 
.B matrix_kb.\fIN\fB.row\-\fIRR\fB\-out bit out
The row scan drive pins.Should be connected to external hardware pins connected
to the keypad. 

.SH PARAMETERS
.TP
.B matrix_kb.\fIN\fB.key_rollover\fR unsigned r/w (default 2)
With most matrix keyboards the scancodes are only unambiguous with 1 or 2 keys
pressed. With more keys pressed phantom keystrokes can appear. Some keyboards
are optimised to reduce this problem, and some have internal diodes so that any
number of keys may be pressed simultaneously. Increase the value of this parameter
if such a keyboard is connected, or if phantom keystrokes are more acceptable
than only two keys being active at one time. 
.TP
.B matrix_kb.\fIN\fB.negative\-logic\fR bit r/w (default 1) only in scan mode
When no keys are pressed a typical digital input will float high. The input will
then be pulled low by the keypad when the corresponding poll line is low.
Set this parameter to 0 if the IO in use requires one row at a time to be high,
and a high input corresponds to a button press. 


